home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / xhdi-110.zoo / xhdispec.eng < prev    next >
Encoding:
Text File  |  1993-05-18  |  16.8 KB  |  428 lines
  1. @(#)XHDI/xhdispec.eng
  2. @(#)Julian F. Reschke, 18. Mai 1993
  3.  
  4. Specification of the `XHDI' cookie, May 18, 1993
  5. ------------------------------------------------
  6.  
  7. Cookie id: "XHDI". The contents of the cookie is the start address of 
  8. a function, which provides procedures for dealing with block storage 
  9. devices. As an additional check, the function is preceded by the long 
  10. constant $27011992.
  11.  
  12. The contents of the XHDI cookie may change (because it can be used by more 
  13. than one driver). Therefore, in some applications (example: DA's) the 
  14. cookie contents must be inquired each time before the handler is called.
  15.  
  16. ALL FUNCTIONS HAVE TO BE CALLED FROM SUPERVISOR MODE. The effects of a 
  17. call in user mode are undefined. All processor registers except d0 are 
  18. preserved. EINVFN is returned for invalid opcodes.
  19.  
  20. Some of the function calls -- notably `XHReadWrite()' -- might be 
  21. implemented by calls to BIOS or XBIOS functions and therefore can activate 
  22. the `Critical Error Handler'. It's the responsibility of the caller to 
  23. switch of the `CEH', if this is needed.
  24.  
  25. Some error codes:
  26.  
  27. TOS error codes:
  28.  
  29. 0:           OK (OK)
  30. -1:          unspecified error (ERROR)
  31. -2:          device not responding (EDRVNR)
  32. -15:         unknown device (EUNDEV)
  33. -32:         invalid function number (EINVFN)
  34. -36:         access denied, device is reserved (EACCDN)
  35. -46:         invalid drive number (EDRIVE)
  36.  
  37. SCSI error codes (ranging from -200 to -455)
  38.  
  39. (-200 - N):  SCSI error code N (the `Additional Sense Code', Byte 12 in the
  40.              `Extended Sense Format', see section 7.2.14 in `draft proposed
  41.              American National Standard for information systems - SMALL
  42.              COMPUTER SYSTEM INTERFACE - 2 (SCSI-2) March 9, 1990').
  43.  
  44. IDE error codes (ranging from -456 to -711)
  45.  
  46. (-456 - N):  IDE error code N (value of the IDE error register)
  47.  
  48. Note: obviously, you can get SCSI error codes only for ACSI or SCSI 
  49. devices. For other device types -- like the IDE drives in the `ST Book' 
  50. or `Falcon 030' (or machines with a third-party IDE interface) -- the 
  51. following assignments may be used:
  52.  
  53. Bit in IDE
  54. error register  meaning                 SCSI error   XHDI error
  55.  
  56. 1               Track 0 not found       $06          -206
  57. 0               DAM not found           $13          -219
  58. 4               ID-Field not found      $12          -218
  59. 7               Bad block mark          $10          -216
  60. 6               Uncorrectable error     $11          -217
  61. 2               Command aborted         $20          -232
  62. 5               Media Change            $28          -240
  63. 3               Media Change requested  $5A          -290
  64.  
  65. (it is recommended to test the bits in the above order).
  66.  
  67. For other devices (like disk drives connected to the floppy controller) 
  68. there may be other, not yet defined, error codes.
  69.  
  70. Parameters are passed the same way as to GEMDOS functions. All values 
  71. are put onto the stack, with the 16 bit opcode last, i.e. at the lowest 
  72. address. The 32 bit result is returned in d0.
  73.  
  74. Wherever it is specified that `the caller may pass a zero pointer' for a 
  75. pointer parameter, then passing such a zero pointer indicates that the 
  76. caller is not interested in the value to be returned. Drivers must always 
  77. check pointers for zero before dereferencing them.
  78.  
  79.  
  80. Definition of data types:
  81.  
  82. UWORD:  16-Bit, unsigned
  83. LONG:   32-Bit, signed
  84. ULONG:  32-Bit, unsigned
  85. char *: 32-Bit, pointer to a zero terminated string
  86.  
  87.  
  88. Terms:
  89.  
  90. major:  Major Device Number
  91.  
  92.            0..7: Devices on the ACSI bus with ATARI-compatible command set
  93.           8..15: Devices on the SCSI bus
  94.          16..17: Devices connected to the IDE interface
  95.          18..63: Extensions as defined in the pun field in the PUN_INFO
  96.                  structure.
  97.              64: Devices on the standard floppy controller
  98.         65..255: Extensions outside the scope of AHDI.
  99.  
  100. minor:  Minor Device Number (for 'major' 0..15: LUN of the ACSI or SCSI
  101.         device), maximal 255.
  102.  
  103. key:    A 16 bit key, returned by `XHReserve()', or 0, if the device is
  104.         not locked or if the key is unknown.
  105.  
  106.  
  107. The XHDI functions:
  108.  
  109. -----------------------------------------------------------------------
  110. Opcode 0: UWORD XHGetVersion (void);
  111.  
  112. Returns the current protocol version. Example: $0119 is Version 1.19 
  113. (the format is similar to that returned by `Sversion()', but high and low 
  114. byte are not reversed). This version of the XHDI specification has the 
  115. version number $0110.
  116.  
  117. -----------------------------------------------------------------------
  118. Opcode 1: LONG XHInqTarget (UWORD major, UWORD minor, ULONG *blocksize,
  119.                             ULONG *device_flags, char *product_name);
  120.  
  121. Returns information about the device specified by `major' and `minor'. 
  122. Reservation made with `XHReserve()' are reflected in `device_flags'.
  123.  
  124. block_size:   Block size for this device (important for `XHReadWrite()').
  125.               Usually 512.
  126.  
  127. device_flags: (Bit set -> Capability available)
  128.  
  129.       Bit 0:  Device is stoppable (XH_TARGET_STOPPABLE)
  130.       Bit 1:  The medium is removable (XH_TARGET_REMOVABLE)
  131.       Bit 2:  The eject mechanism can be locked 
  132.               (XH_TARGET_LOCKABLE)
  133.       Bit 3:  The device can physically eject the medium
  134.               (XH_TARGET_EJECTABLE)
  135.       Bit 31: The device is currently reserved (XH_TARGET_RESERVED).
  136.  
  137.               All other bits are reserved, drivers should set them to zero.
  138.  
  139. product_name: Product name of the device, similar to the information
  140.               returned by the SCSI command INQUIRE (max. 33 characters
  141.               incl. terminating zero). If this information is not
  142.               available, the driver should return a zero length string.
  143.  
  144. Note: the caller may pass a zero pointer for `blocksize', `device_flags' 
  145. and `product_name'.
  146.  
  147. Note: for IDE devices, product name information might have to be truncated 
  148. to fit into 32 characters. See `XHInqTarget2'.
  149.  
  150. -----------------------------------------------------------------------
  151. Opcode 2: LONG XHReserve (UWORD major, UWORD minor, UWORD do_reserve,
  152.                           UWORD key);
  153.  
  154. Reserves or releases a device. `XHLock()', `XHStop()' and `XHEject()' only 
  155. work for reserved devices if the correct key parameter is passed.
  156.  
  157. Example: take a virtual memory manager which has locked a removable hard 
  158. disk with the swap partition. You don't want the user to be able to unlock 
  159. this device with a CPX module!
  160.  
  161. On success, a 16 bit key is returned.
  162.  
  163. do_reserve: (1) Reserve or (0) release.
  164. key:        (only used for release).
  165.  
  166. -----------------------------------------------------------------------
  167. Opcode 3: LONG XHLock (UWORD major, UWORD minor, UWORD do_lock,
  168.                        UWORD key);
  169.  
  170. Locks or unlocks the eject mechanism of the device.
  171.  
  172. do_lock: (1) Lock or (0) unlock.
  173. key:     if the device is reserved pass the key, otherwise zero.
  174.  
  175. -----------------------------------------------------------------------
  176. Opcode 4: LONG XHStop (UWORD major, UWORD minor, UWORD do_stop,
  177.                        UWORD key);
  178.  
  179. Stops (ships) or starts the device.
  180.  
  181. do_stop: (1) Stop or (0) start.
  182. key:     if the device is reserved pass the key, otherwise zero.
  183.  
  184. Note: if the drive is accessed, the driver should restart it without an
  185.       explicit restart call.
  186.  
  187. -----------------------------------------------------------------------
  188. Opcode 5: LONG XHEject (UWORD major, UWORD minor, UWORD do_eject,
  189.                         UWORD key);
  190.  
  191. Ejects or inserts the medium.
  192.  
  193. do_eject: Eject (1) or insert (0) medium.
  194. key:      if the device is reserved pass the key, otherwise zero.
  195.  
  196. -----------------------------------------------------------------------
  197. Opcode 6: ULONG XHDrvMap (void);
  198.  
  199. Returns a bit mask of BIOS devices supported by the XHDI driver(s) (as the 
  200. return value from `Drvmap()').
  201.  
  202. -----------------------------------------------------------------------
  203. Opcode 7: LONG XHInqDev (UWORD bios_device, UWORD *major, UWORD *minor,
  204.                          ULONG *start_sector, BPB *bpb);
  205.  
  206. Returns major device number, minor device number, starting sector and BPB 
  207. of a given BIOS device (Note: getting the BPB this way will NOT reset the 
  208. internal media change state).
  209.  
  210. Note: the caller provides a pointer to the BPB structure, which is filled 
  211. by the driver.
  212.  
  213. Return values: OK, EDRNVR (device not responding, eg. medium not 
  214. inserted), EDRIVE (wrong BIOS device number) or some other applicable 
  215. error code. If the error code is EDRVNR, `major' and `minor' contain the 
  216. correct values anyway.
  217.  
  218. If `start_sector' is $FFFFFFFF, the device is only temporarily 
  219. inaccessible (example: you have inserted a cartridge with two partitions, 
  220. but three drive bits have been reserved for the device).
  221.  
  222. The BPB is invalid if the structure element `recsiz' is zero.
  223.  
  224. Note: a file system is fully described by major and minor device number 
  225. and the starting block number. This does NOT mean, that it is necessarely 
  226. a FAT file system.
  227.  
  228. Note: the caller may pass a zero pointer for `major', `minor', 
  229. `start_sector' and `bpb'.
  230.  
  231. -----------------------------------------------------------------------
  232. Opcode 8: LONG XHInqDriver (UWORD bios_device, char *name, char *version,
  233.                             char *company, UWORD *ahdi_version,
  234.                             UWORD *maxIPL);
  235.  
  236. Gets information about the driver for the bios_device.
  237.  
  238. name:         Name of driver (max. 17 characters).
  239. version:      String with version number (max. 7 characters).
  240. company:      Name of company/programmer (max. 17 characters).
  241. ahdi_version: AHDI version level (as defined in the PUN_INFO structure).
  242. maxIPL:       Highest IPL under which the driver can work (usually 5 for
  243.               drivers which use _hz_200 for timing loops).
  244.  
  245. Note: the caller may pass a zero pointer for `name', `version', 
  246. `company', `ahdi_version' and `maxIPL'.
  247.  
  248. -----------------------------------------------------------------------
  249. Opcode 9: LONG XHNewCookie (ULONG newcookie);
  250.  
  251. - OPTIONAL function, may return EINVFN -
  252.  
  253. /* send translations to julian@math.uni-muenster.de */
  254.  
  255.  
  256. ------------------------------------------------------------------------
  257. Opcode 10: LONG XHReadWrite (UWORD major, UWORD minor, UWORD rwflag,
  258.                              ULONG recno, UWORD count, void *buf);
  259.  
  260. Read or write physical blocks.
  261.  
  262. rwflag:       Bits 0..2: as defined in the AHDI Release Notes (3.00, April
  263.               18, 1990). Bit 3 (physical mode) is ignored. All other bits
  264.               are reserved and should be set to zero.
  265. recno:        block number
  266. count:        block count
  267. buf:          pointer to buffer
  268.  
  269. -----------------------------------------------------------------------
  270. Opcode 11: LONG XHInqTarget2 (UWORD major, UWORD minor, ULONG *blocksize,
  271.                               ULONG *device_flags, char *product_name,
  272.                               UWORD stringlen);
  273.  
  274. - only with XHDI version 1.01 and above -
  275.  
  276. Returns information about the device specified by `major' and `minor'. 
  277. Reservation made with `XHReserve()' are reflected in `device_flags'.
  278.  
  279. block_size:   Block size for this device (important for `XHReadWrite()').
  280.               Usually 512.
  281.  
  282. device_flags: (Bit set -> Capability available)
  283.  
  284.       Bit 0:  Device is stoppable (XH_TARGET_STOPPABLE)
  285.       Bit 1:  The medium is removable (XH_TARGET_REMOVABLE)
  286.       Bit 2:  The eject mechanism can be locked 
  287.               (XH_TARGET_LOCKABLE)
  288.       Bit 3:  The device can physically eject the medium
  289.               (XH_TARGET_EJECTABLE)
  290.       Bit 31: The device is currently reserved (XH_TARGET_RESERVED).
  291.  
  292.               All other bits are reserved, drivers should set them to zero.
  293.  
  294. product_name: Product name of the device, similar to the information
  295.               returned by the SCSI command INQUIRE (max. `stringlen'    
  296.               characters incl. terminating zero). If this information is 
  297.               not available, the driver should return a zero length string.
  298.  
  299. stringlen:    Length of string buffer passed in `product_name'.
  300.  
  301. Note: the caller may pass a zero pointer for `blocksize', `device_flags' 
  302. and `product_name'. Product names of IDE devices may contain up to 40 
  303. characters.
  304.  
  305.  
  306. -----------------------------------------------------------------------
  307. Opcode 12: LONG XHInqDev2 (UWORD bios_device, UWORD *major, UWORD *minor,
  308.                            ULONG *start_sector, BPB *bpb, ULONG *blocks,
  309.                            char *partid);
  310.  
  311. - only with XHDI version 1.10 and above -
  312.  
  313. Returns major device number, minor device number, starting sector, BPB, 
  314. size and partition ID of a given BIOS device (Note: getting the BPB this 
  315. way will NOT reset the internal media change state).
  316.  
  317. Note: the caller provides a pointer to the BPB structure, which is 
  318. filled by the driver.
  319.  
  320. Return values: OK, EDRNVR (device not responding, eg. medium not 
  321. inserted), EDRIVE (wrong BIOS device number) or some other applicable 
  322. error code. If the error code is EDRVNR, `major' and `minor' 
  323. `start_sector' contain the correct values anyway.
  324.  
  325. If `start_sector' is $FFFFFFFF, the device is only temporarily 
  326. inaccessible (example: you have inserted a cartridge with two partitions, 
  327. but three drive bits have been reserved for the device).
  328.  
  329. The BPB is invalid if the structure element `recsiz' is zero.
  330.  
  331. If the partition ID isn't available (possible reason: no standard Atari 
  332. root sector or no root sector at all), an empty string is returned.
  333.  
  334. Note: a file system is fully described by major and minor device number and
  335. the starting block number. This does NOT mean, that it is necessarely a FAT
  336. file system.
  337.  
  338. Note: the caller may pass a zero pointer for `major', `minor', 
  339. `start_sector', `bpb', `blocks' and `partid'.
  340.  
  341.  
  342. -----------------------------------------------------------------------
  343. Opcode 13: LONG XHDriverSpecial (ULONG key1, ULONG key2,
  344.                                  UWORD subopcode, void *data);
  345.  
  346. - OPTIONAL function, may return EINVFN -
  347.  
  348. This opcode may be used for driver specific extensions. It's up to the 
  349. driver how to interpret the arguments in `subopcode' and `data'. `key1' 
  350. and `key2' are used to specify for which driver the call is: `key1' should 
  351. contain four printable ASCII characters, `key2' a `random' ULONG value 
  352. (example: date of definition in BCD format).
  353.  
  354.  
  355. -----------------------------------------------------------------------
  356. Opcode 14: LONG XHGetCapacity (UWORD major, UWORD minor, ULONG *blocks,
  357.                                ULONG *blocksize);
  358.  
  359. - OPTIONAL function, may return EINVFN -
  360.  
  361. This functions returns the number of adressable sectors in `blocks' 
  362. and their size in `blocksize'. Note that -- depending of the device used 
  363. -- this function may need several seconds to complete.
  364.  
  365.  
  366. ------------------------------------------------------------------------
  367.  
  368.  
  369. How to install more than one XHDI driver
  370. ----------------------------------------
  371.  
  372. (1) During the installation, check if the cookie is alreay set. If so:
  373.     
  374. (2) For `XHGetVersion()' first jump through the old vector and return the
  375.     minimum of this and your own version number.
  376.     
  377. (3) For `XHDrvmap()' first jump through the old vector and then or-in the
  378.     drive bits for the devices supported by you.
  379.     
  380. (4) For all other functions: check, if one of `your' devices. If not, jump
  381.     through the old vector.
  382.  
  383.  
  384. ------------------------------------------------------------------------
  385.  
  386. Partition type `RAW'
  387. --------------------
  388.  
  389. XHDI-1.10 compliant drivers shall support the third partition type `RAW' 
  390. (in addition to `GEM' and `BGM'). For these partitions, the following 
  391. should be true:
  392.  
  393. (1) The partition size is `arbitrary' (32 bit sector numbers).
  394.  
  395. (2) The partition can be accessed as BIOS device; Getbpb() returns a
  396.     NULL pointer (so that GEMDOS won't access it; however, calling
  397.     Getbpb() resets the driver internal media change state).
  398.  
  399. (3) `Rwabs()' (in physical or logical mode) and `XHReadWrite()' may be
  400.     used to access the partition. The physical block size of the medium
  401.     is used (see `XHInqTarget()').
  402.  
  403. (4) `XHInqDev2()' (as compared to `XHInqDev()') returns size and type of
  404.     the partition.
  405.  
  406. These extensions have been made to make it easier to create drivers
  407. for new filesystems for MiNT (like the Minix file system).
  408.  
  409.  
  410. ------------------------------------------------------------------------
  411.  
  412. Recommended partition types
  413. ---------------------------
  414.  
  415. BGM     GEMDOS partition > 16MB
  416. GEM     GEMDOS partition < 16MB
  417. RAW     see above
  418.  
  419. The following types can be supported optionally (for example with a 
  420. configurable list of partition ID's in the driver).
  421.  
  422. MAC     MAC HFS partition, should be handled like `RAW'
  423. MIX     Minix partition, should be handled like `RAW'
  424. SWP     Swap partition, should be handled like `RAW'
  425. UNX     ASV (Atari System V) partition, should be handled like `RAW'
  426.  
  427.  
  428.